.dmg/Serious Software/NetCloak 3.0.3 Pro CD demo.sea/NetCloak 3.0.3 Pro CD demo/NetCloak Introduction/NetCloak/NCUsersGuide/Figures/NC.GIF){kind=small}
User's Guide
Commands: Variables
Contents
|
Version 3.0 User's Guide |
Commands: Variables |
Previous |
Next Contents |
NetCloak supports four distinct types of variables: Local, User, Global, and Cookies. The first three types are stored by NetCloak. Cookies are different from the others in that they are stored at the client, so they will be discussed separately later.
Variables have a name and a value. A variable name consists of alphanumeric characters, may not contain quote marks, expression operators (+,-,*,/, &), the '#' character, or whitespace characters, and may not begin with a digit or an exclamation point. A variable may have any text or numeric value.
Local variables can be used only within a single HTML page. Local variables can be set at the top of the page and used repeatedly within the page, but once the page has been served completely the variable is forgotten. Local variables are useful for storing data that only needs to be used on another part of the same page, such as in math functions, simplifying complicated SHOW/HIDE expressions, passing variables into macros, looping in a REPEAT command, etc.
User variables remain in effect for a particular user during the time they are visiting your site. When a form is submitted to NetCloak, the fields on the form become NetCloak user variables automatically. User variables will not affect users other than the user they are set for, but they persist between page accesses for up to one hour or until another form is submitted by the same user. User variables are tracked either by the visitor's IP address or by a default cookie that can be generated by NetCloak. Note that when the user does not have a browser which supports cookies, then user variables will be tracked by IP address even if you set the default cookie. See the SET_COOKIE command description for information about creating a default cookie.
Global variables are variables that are retained indefinitely and have a single value for all pages being served to all users. You can use globals as mini-macros, making short blocks of text (a few characters or words) easy to use throughout your site. Global variables also allow you to have the actions taken by one user on your site to impact others. For example, you could have a form that allowed you, as the Webmaster, to turn on and off various portions of your Web site, by showing and hiding links to pages based on global variables that were affected by form submissions. You could also create multi-user games, implement opinion polls, and more.
Global variables can be created and updated one of three ways:
NetCloak allows you to create HTML forms that ask the user to enter information and then use that information in your pages. The contents of the form are then automatically used to create User Variables.
Each field of your HTML form will have a name. Once the form is submitted, each field becomes a NetCloak User variable with the same name, whose value is the value entered into the field by the user. The variable can then be referenced by name on subsequent pages. You can either show the variables to the user in the text of your HTML document, or use SHOW and HIDE to have your page change based on what the user entered into the fields of the form.
The first step is to create an input form that uses the POST method for form processing. In the ACTION field of your FORM command, you will need to specify the URL of a document that will be processed by NetCloak. NetCloak will store data entered on the form and then serve the file specified. Here is an example of an HTML form:
<FORM method=POST action="/VarDisplay.html"> Please fill out this simple form:<P> Name:
<INPUT TYPE="text" NAME="YourName" SIZE="32" MAXLENGTH="32"> <P> Organization:
<SELECT name="Organization"> <OPTION selected>Commercial
<OPTION>K12 Education
<OPTION>Higher Education
<OPTION>Government
</SELECT> <P> Check here <INPUT NAME="MyCheckBox" TYPE=checkbox VALUE="CHECKED"> <INPUT TYPE=submit VALUE="Submit Form"> <INPUT TYPE=reset VALUE="Start Over"> </FORM>
In this example, the action specified is "/VarDisplay.html", which is simply the name of the html file we would like served when the user clicks the "Submit Form" button. Of course, the page will need to be served by NetCloak, so the file name specified in the action must end with an extension that is mapped to NetCloak. The example assumes that the Web server is configured to cloak all HTML files.
Once a form has been processed, the fields on the form become User variables that may be used within cloaked documents.
Some form variables can have multiple values. These are called "multivalue" variables. An example is a set of checkboxes that all have the same field name but different values, or a SELECT field with the MULTIPLE attribute (which is usually displayed as a list box that allows multiple selections). NetCloak allows you to access all of the values of a multivalue variable, using square brackets after the variable name which include the number of the instance you want to use. For example, to access the third instance of a variable named "Toppings", you could write:
<INSERT_VARIABLE Toppings[3]>
Furthermore, you can use the name of another variable within the square brackets to access an instance of a multivalue variable, like this:
<INSERT_VARIABLE Toppings[gDailySpecial]>
This notation is supported in all NetCloak INSERT, SHOW, and HIDE commands, as well as the REPEAT command.
Variables can be assigned values either by user input or by using the SET_LOCAL, SET_VARIABLE, or SET_GLOBAL commands. Each of the SET commands sets the variable "varName" to the given value. The equal sign ("=") is optional. The "value" can be a string, a number, or another local, user, global, counter or cookie variable (see below for information about cookies). In addition, five operators can currently be used to create a value from an expression. They are:
+ Performs simple addition.
- Subtracts the second value from the first.
* Multiplies two values.
/ Divides the first value by the second.
& Concatenates two values ("adds" the strings).
For example, to put the value of "2 + 2" into the local variable "Four", you could use the command:
<SET_LOCAL Four = 2 + 2>
Another way to put the number 4 into the variable "Four" would be:
<SET_LOCAL Two = 2> <SET_LOCAL Four = Two * 2>
We could also set a variable called "TwentyTwo" by doing something like:
<SET_LOCAL Two = 2> <SET_LOCAL TwentyTwo = Two & "2">
When performing numeric operations in SET commands, NetCloak gives the resulting variable the same number of decimal places as the parameter with the most decimal places on the right-hand side of the equal sign. Thus, if no decimal places are given, then NetCloak will display no decimal places when the resulting variable is INSERTed into a page. Conversely, the following code:
<SET_LOCAL a = 12.3456> <SET_LOCAL b = 3> <SET_LOCAL c = a * b> <INSERT_LOCAL c>
...will cause the value "37.0368" to be inserted into the page. See the INSERT variable commands, below, for more information about controlling the number of decimal places displayed.
You can include multiple operators in the same SET command, but be aware that NetCloak does not honor any operator precedence rules - it merely works from left to right. Thus, all of the following are allowed by NetCloak:
<SET_LOCAL newURL = "http://" & gHostName & "/" & <INSERT_THISURL>> <SET_LOCAL TwoTwentyTwo = 200 + 20 + Two> <SET_LOCAL WhoKnows = 200 - 20 / 2> <SET_LOCAL NotOne = 1.0/2.0 + 1.0/2.0>
...but only the first two will produce results you might expect. The third command assigns a value of 90 to the variable "WhoKnows"; the last assigns "NotOne" a value of 0.8.
It is standard practice to put strings in quotes and leave numeric values without, but NetCloak will accept a number in quotes or a string without. Also, the equal sign is not required, though is encouraged for readability, especially when performing numeric operations.
When assigning a variable, you can reference any local, user, global, counter, or cookie variable on the right-hand side of the equal sign, without using a nested INSERT command. So, you can set a local variable to the value currently held in a global, or a global variable to the current value of a counter.
For example, let's say you have a counter on your home page called "HomeHits", and another counter on every page of your server called "TotalHits". You could display the percentage of hits your home page receives on your site with something like:
<SET_LOCAL HHTemp = HomeHits * 100> <SET_LOCAL Percentage = HHTemp / TotalHits> Home Page: <INSERT_LOCAL Percentage>%
To determine the value of a variable found on the right-hand side of the equal sign in a SET command, NetCloak searches for variables in order from most-specific scope to least-specific scope. In other words, it looks for variables that are most-specific to the current page first. It searches for variables in this order:
Thus, if you have defined a local variable and global variable with the same name, the value of the local variable will be used first. If NetCloak does not find any matching variable name, the variable name itself is used as the value of that parameter.
These commands will place the contents of the variable into the page. The value inserted may be a computed variable created using a SET command, or it could be the field from a user-entered form.
For example, after the form above has been filled out and submitted, you could use the following command to display the user's name:
Your name is: <INSERT_VARIABLE YourName>
Inserted variables will appear as you would expect, with the value of the variable inserted at the point at which the INSERT command is placed. Numeric values will be displayed as numbers (not an ASCII representation of the value) so that a variable with a value of 65 will be displayed as "65" and not the letter "A".
If the variable value is a number, you can control the number of decimal places displayed by providing the optional "decimalPlaces" parameter. If omitted, all decimal places from the value will be displayed. This parameter is ignored if the variable's value contains any characters other than a digit, period, plus, or minus character. For instance, the following code:
<SET_LOCAL a = 12.3456> <SET_LOCAL b = 3> <SET_LOCAL c = a * b> <INSERT_LOCAL c 1>
...will insert the value "37.0" into the page.
Important Note! It is possible for NetCloak to incorrectly identify users and confuse the variables. This can occur when browsers don't support cookies (or are configured not to allow them) and/or when user IP addresses are being dynamically assigned or users connect through a proxy server. For this reason, you should not use User variables to show and hide secure information, or for mission critical applications. In cases where you are certain that each user will have a unique IP address (for example, possibly on your internal LAN) User variables will be reliable.
Also note that expressions used to create values for variables ("+", "-", etc.) cannot be used in INSERT commands. To display a computed value, you must SET a variable first then reference it by name in the INSERT command.
Any HTML text that follows HIDE_LOCAL, HIDE_VARIABLE, or HIDE_GLOBAL will be hidden from those users when the specified variable satisfies the comparison to any one of the listed values. If the comparison operator is not specified, text is hidden if the variable's value contains any of the listed values.
An example should make this more clear. Assuming that the input form above has been filled out and submitted by the user, we could use:
<SHOW> <HIDE_VARIABLE YourName CONTAINS "J"> Your name does not contain a J.
<SHOW>
Here, the variable YourName (what the user entered into the field "YourName" on the input form) is checked to see if it contains a "J". If it does, text will be hidden, and the phrase "Your name does not contain a J" will not be seen. To see if the checkbox was checked, we could use:
<SHOW> <HIDE_VARIABLE MyCheckBox IS "CHECKED"> You didn't check the check box!
Frequently, it is necessary to check that a variable value is not empty, as when a user is filling out form fields. You can check for non-empty variables using the EXISTS operator, or by simply not specifying a value in the HIDE command. For example:
<SHOW> <HIDE_VARIABLE EXISTS YourName> You didn't enter a name!
<SHOW>
The text "You didn't enter a name!" will only appear if the "YourName" field was left blank in the form.
These commands operates exactly like HIDE commands above except that they turn the text stream on instead of turning it off. To continue the example from above, we could also show a message when the checkbox is checked, by using:
<HIDE> <SHOW_VARIABLE MyCheckBox IS "CHECKED"> You checked the check box!
<SHOW>
This is a handy utility command which displays a list of all the defined user variables for the current page. The list of variables is formatted according to the HTML text inserted between the <VARIABLE_LIST> and </VARIABLE_LIST> tags. The HTML text is repeated once for each defined variable. Within this HTML text, any occurrence of the special tag <VARNAME> is replaced with the variable name, and the special tag <VARVALUE> is replaced with the value of that variable. An example will make things clearer. Suppose a user has submitted a form with three fields: a field named "Crust" with a value of "Deep Dish", a field named "Topping" with a value of "Pepperoni", and a field named "Size" with a value of "Medium". Then the following code:
<VARIABLE_LIST> <B><VARNAME>:</B> <VARVALUE> </VARIABLE_LIST>
...will cause the following text to be displayed in the browser:
<B>Crust:</B> Deep Dish
<B>Topping:</B> Pepperoni
<B>Size:</B> Medium
This command is very handy for debugging purposes, as well as for passing variables from one form to another when the variable names may not be known in advance.
| Copyright © 1996-1999 Maxum Development Corporation http://www.maxum.com/ |
Previous |
Next Contents |